{/* Copyright 2020 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '@react-spectrum/docs';
export default Layout;

import docs from 'docs:@react-spectrum/icon';
import {HeaderInfo, PropTable} from '@react-spectrum/docs';
import packageData from '@react-spectrum/icon/package.json';

```jsx import
import {Flex} from '@react-spectrum/layout';
import {Icon} from '@react-spectrum/icon';
```

---
category: Icons
---

# Custom Icons

Custom icons can be used by wrapping them in an Icon component.

<HeaderInfo
  packageData={packageData}
  componentNames={['Icon']}
  sourceData={[
    {type: 'Spectrum', url: 'https://spectrum.adobe.com/page/iconography/'}
  ]}
  since="3.0.0" />

## Example

```tsx example export=true
function CustomIcon(props) {
  return(
    <Icon {...props}>
      <svg viewBox="0 0 36 36">
        <path d="M18.477.593,22.8,12.029l12.212.578a.51.51,0,0,1,.3.908l-9.54,7.646,3.224,11.793a.51.51,0,0,1-.772.561L18,26.805,7.78,33.515a.51.51,0,0,1-.772-.561l3.224-11.793L.692,13.515a.51.51,0,0,1,.3-.908L13.2,12.029,17.523.593A.51.51,0,0,1,18.477.593Z" />
      </svg>
    </Icon>
  );
}

<CustomIcon aria-label="Star" />
```

Wrapping the SVG with Icon will ensure it receives proper styling when used within React Spectrum components:

```tsx example
import {Button, Text} from '@adobe/react-spectrum';

<Button variant="primary">
  <CustomIcon />
  <Text>Favorite</Text>
</Button>
```

## Sizing

Icons support t-shirt sizing. When used inside another React Spectrum component, they'll generally be sized automatically,
but if you use icons standalone, you can use the `size` prop to control the sizing. The default size is "M" in medium scale
(desktop), and "L" in large scale (mobile).

```tsx example
<Flex gap="size-100">
  <CustomIcon aria-label="XXS Star" size="XXS" />
  <CustomIcon aria-label="XS Star" size="XS" />
  <CustomIcon aria-label="S Star" size="S" />
  <CustomIcon aria-label="M Star" size="M" />
  <CustomIcon aria-label="L Star" size="L" />
  <CustomIcon aria-label="XL Star" size="XL" />
  <CustomIcon aria-label="XXL Star" size="XXL" />
</Flex>
```

## Coloring

Icons support four Spectrum semantic colors: `negative`, `notice`, `positive`, and `informative`. Icons within React Spectrum components typically
have their colors styled appropriately, but you can use the `color` prop to adjust the color of any standalone icons.

```tsx example
<Flex gap="size-100">
  <CustomIcon aria-label="Default Star" />
  <CustomIcon aria-label="Negative Star" color="negative" />
  <CustomIcon aria-label="Notification Star" color="notice" />
  <CustomIcon aria-label="Positive Star" color="positive" />
  <CustomIcon aria-label="Informative Star" color="informative" />
</Flex>
```

## Labeling

By default, icons are considered decorative, and are hidden from assistive technology. When used within a component like a button
that has no label, an `aria-label` should be provided to the parent component. If used standalone, an `aria-label` can be provided
to the icon itself.

## Props

<PropTable component={docs.exports.Icon} links={docs.links} />
